Skip to content

Conversation

sunfishcode
Copy link
Member

This adds API documentation support for std::os::wasi modeled after
how std::os::unix works, so that WASI can be documented here along
with the other platforms.

Two changes of particular interest:

  • This changes the AsRawFd for io::Stdin for WASI to return
    libc::STDIN_FILENO instead of sys::stdio::Stdin.as_raw_fd() (and
    similar for Stdout and Stderr), which matches how the unix
    version works. STDIN_FILENO etc. may not always be explicitly
    reserved at the WASI level, but as long as we have Rust's std and
    libc, I think it's reasonable to guarantee that we'll always use
    libc::STDIN_FILENO for stdin.

  • This duplicates the osstr2str utility function, rather than
    trying to share it across all the configurations that need it.

r? @alexcrichton

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 22, 2021
@alexcrichton
Copy link
Member

@bors: r+

@bors
Copy link
Collaborator

bors commented Feb 22, 2021

📌 Commit 643d2ce3e2de481593bc4aaee81f1df361680864 has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 22, 2021
@camelid camelid added O-wasm Target: WASM (WebAssembly), http://webassembly.org/ A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Feb 23, 2021
@bors
Copy link
Collaborator

bors commented Feb 23, 2021

☔ The latest upstream changes (presumably #82430) made this pull request unmergeable. Please resolve the merge conflicts.

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 23, 2021
@rust-log-analyzer

This comment has been minimized.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.
@alexcrichton
Copy link
Member

@bors: r+ delegate+

@bors
Copy link
Collaborator

bors commented Feb 23, 2021

📌 Commit 132ec26 has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 23, 2021
@bors
Copy link
Collaborator

bors commented Feb 23, 2021

✌️ @sunfishcode can now approve this pull request

@CDirkx
Copy link
Contributor

CDirkx commented Feb 23, 2021

Currently the documentation does not build for all platforms:

pub mod prelude {
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::ffi::{OsStrExt, OsStringExt};
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::fs::FileTypeExt;
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::fs::{DirEntryExt, FileExt, MetadataExt, OpenOptionsExt};
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
}

All these should use super:: instead of crate::sys::ext because with this change, when documenting on windows for example, sys::ext will be the windows ext, not the wasi one.

Also, technically if one would ever document targeting wasi (not currently possible I think) the module os::wasi would be defined twice because of the missing #[cfg(not(doc))]:

#[cfg(target_os = "wasi")]
pub mod wasi;

and now wasi can also be added to the comment at the top of os/mod.rs:

// When documenting libstd we want to show unix/windows/linux modules as these are the "main

@CDirkx
Copy link
Contributor

CDirkx commented Feb 23, 2021

Capture

Rustdoc will also need to be updated, but that can be a followup.

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 24, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? `@alexcrichton`
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 24, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? ``@alexcrichton``
@JohnTitor
Copy link
Member

Failed in rollup: #82472 (comment)
@bors r-

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 24, 2021
WASI's `RawFd` is a `u32`, while `libc` uses `c_int`.
This ensures that these names resolve to the right place even when
building the WASI support on other platforms for generating the
documentation.
@sunfishcode
Copy link
Member Author

Thanks! I've now fixed the crate::sys::ext paths, added the cfg(not(doc)) to the main wasi module, and added "wasi" to the "main module" comment.

@alexcrichton
Copy link
Member

@bors: r+

@bors
Copy link
Collaborator

bors commented Feb 25, 2021

📌 Commit 7d5242a has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 25, 2021
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 26, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? `@alexcrichton`
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 27, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? ``@alexcrichton``
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 27, 2021
Rollup of 14 pull requests

Successful merges:

 - rust-lang#81794 (update tracking issue for `relaxed_struct_unsize`)
 - rust-lang#82057 (Replace const_cstr with cstr crate)
 - rust-lang#82370 (Improve anonymous lifetime note to indicate the target span)
 - rust-lang#82394 (:arrow_up: rust-analyzer)
 - rust-lang#82396 (Add Future trait for doc_spotlight feature doc)
 - rust-lang#82404 (Test hexagon-enum only when llvm target is present)
 - rust-lang#82419 (expand: Preserve order of inert attributes during expansion)
 - rust-lang#82420 (Enable API documentation for `std::os::wasi`.)
 - rust-lang#82421 (Add a `size()` function to WASI's `MetadataExt`.)
 - rust-lang#82442 (Skip emitting closure diagnostic when closure_kind_origins has no entry)
 - rust-lang#82473 (Use libc::accept4 on Android instead of raw syscall.)
 - rust-lang#82482 (Use small hash set in `mir_inliner_callees`)
 - rust-lang#82490 (Update cargo)
 - rust-lang#82494 (Substitute erased lifetimes on bad placeholder type)

Failed merges:

 - rust-lang#82448 (Combine HasAttrs and HasTokens into AstLike)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit f5b68a4 into rust-lang:master Feb 27, 2021
@rustbot rustbot added this to the 1.52.0 milestone Feb 27, 2021
@sunfishcode sunfishcode deleted the wasi-docs branch February 27, 2021 15:30
sunfishcode added a commit to sunfishcode/rust that referenced this pull request Feb 27, 2021
As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc
how to display WASI.

[this comment]: rust-lang#82420 (comment)
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Mar 2, 2021
Teach rustdoc how to display WASI.

As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc
how to display WASI.

[this comment]: rust-lang#82420 (comment)

r? `@alexcrichton`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools O-wasm Target: WASM (WebAssembly), http://webassembly.org/ S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants